added custom one-site matrix observables for non-qubit local dimensions, including named position observables by linusschulte · Pull Request #497 · munich-quantum-toolkit/yaqs

linusschulte · 2026-07-08T06:59:22Z

Description

This PR adds support for one-site higher-level/qudit observables using new LocalOperator in order to enable measurement of things like physical position.

Tests cover Observable construction from local matrices, MPS expectation evaluation on non-qubit sites, dimension-mismatch errors, and the proper expected trapped-ion trajectory.

Note: Local Observables are still called "Gates" due to qubit-only heritage. That might be a bit misleading for non-logical operators but renaming that consistently is outside of this PR's scope.

Checklist

The pull request only contains commits that are focused and relevant to this change.
I have added appropriate tests that cover the new/changed functionality.
I have updated the documentation to reflect these changes.
I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
I have added migration instructions to the upgrade guide (if needed).
The changes follow the project's style guidelines and introduce no new warnings.
The changes are fully tested and pass the CI checks.
I have reviewed my own code changes.

If PR contains AI-assisted content:

PR was assisted by ChatGPT Codex 5.5 via VS Code Codex Plugin

I have disclosed the use of AI tools in the PR description as per our AI Usage Guidelines.
AI-assisted commits include an Assisted-by: [Model Name] via [Tool Name] footer.
I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

…measurement

Signed-off-by: linusschulte <119408387+linusschulte@users.noreply.github.com>

aaronleesander · 2026-07-08T07:33:40Z

@linusschulte Can you do a couple things

I don't want the user to have to import Observable. If you check previous usage, users just type Observable("name", site). Can you change it to be more user-friendly somehow? If not, let me know and we can look through it
There was just a release so the CHANGELOG point should be moved up under [Unreleased]. You might need to add an added header like in the previous ones.

codecov · 2026-07-08T07:45:30Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

linusschulte · 2026-07-08T08:18:18Z

Regarding your first review point:
Are you looking for something like Observable("position", site)? The constructor needs the actual grid values, so I don't think it can be done without passing additional context. The next best thing I can think of is something like Observable.position(positions, site), but that's really just a wrapper for np.diag, and I'm not sure how much higher that ranks on the user-friendliness scale.

Signed-off-by: linusschulte <119408387+linusschulte@users.noreply.github.com>

aaronleesander · 2026-07-30T11:52:27Z

@coderabbitai review

coderabbitai · 2026-07-30T11:52:33Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai · 2026-07-30T11:56:44Z

📝 Walkthrough

Summary by CodeRabbit

New Features
- Added support for custom one-site observables on systems with non-qubit local dimensions.
- Added local matrix and position observables, including configurable position bases.
- Simulation results can now report expectation values for custom observables.
Bug Fixes
- Improved validation for observable dimensions, sites, and unsupported configuration parameters.
- Corrected handling of one- and two-site observables, including periodic boundaries.
Documentation
- Updated observable configuration guidance and the trapped-ion simulation example.

Walkthrough

This PR adds custom matrix and position observables for non-qubit local dimensions, extends Observable construction, updates MPS expectation and application routing, and revises trapped-ion documentation, tests, and changelog entries.

Changes

Custom Observable Support

Layer / File(s)	Summary
Local and position gate types `src/mqt/yaqs/core/libraries/gate_library.py`	Adds validated `LocalOperator` and `Position` gates and exposes them through `GateLibrary`.
Observable construction `src/mqt/yaqs/core/data_structures/simulation_parameters.py`, `tests/core/data_structures/test_simulation_parameters.py`	Supports matrix inputs and keyword-configured named observables while preserving explicit PVM handling and validation.
MPS observable routing `src/mqt/yaqs/core/data_structures/mps.py`, `tests/core/data_structures/test_mps.py`	Routes by interaction type, validates dimensions, handles periodic two-site application, and adds coverage for non-qubit observables.
Trapped-ion example and validation `docs/examples/trapped_ion.md`, `docs/examples/simulation_parameters.md`, `tests/core/data_structures/test_mpo.py`, `CHANGELOG.md`	Uses position expectation values in the trapped-ion example, documents configured observables, and adds trapped-ion validation and changelog entries.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Example
  participant Observable
  participant AnalogSimParams
  participant Simulator
  participant Result
  Example->>Observable: create position observable
  Example->>AnalogSimParams: configure observable sampling
  AnalogSimParams->>Simulator: run evolution
  Simulator-->>Result: return expectation_values
  Result-->>Example: provide position expectation

Possibly related PRs

munich-quantum-toolkit/yaqs#430: Modifies the shared observable and gate infrastructure.
munich-quantum-toolkit/yaqs#477: Modifies MPS measurement and expectation paths.

Suggested labels: enhancement

Suggested reviewers: aaronleesander, denialhaag

Poem

I’m a bunny with a matrix to hop,
New position gates now point and stop.
Through MPS paths the values flow,
Trapped-ion plots begin to glow.
Tests thump softly—green as spring,
Custom observables do their thing!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 96.55% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: adding custom one-site matrix observables, including position observables.
Description check	✅ Passed	The description includes the change summary, motivation, checklist, and AI disclosure, and it is mostly complete against the template.

✨ Finishing Touches

✨ Simplify code

Create PR with simplified code

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mqt/yaqs/core/data_structures/mps.py`:
- Around line 1121-1124: In the two-site observable branch identified by
observable.gate.interaction == 2, validate that exactly two sites are provided
and that mat has shape (d_i * d_j, d_i * d_j) before indexing sites or
performing contraction; raise the documented ValueError for invalid input while
preserving the existing valid-input path.

In `@src/mqt/yaqs/core/libraries/gate_library.py`:
- Around line 1698-1705: Update the position validation before the dtype
coercion in the constructor’s initialization block to detect complex-valued
inputs and raise ValueError for them, rather than allowing np.asarray to discard
imaginary components. Preserve the existing non-empty, one-dimensional,
finite-value checks and diagonal matrix initialization for valid real positions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 72d073df-31a2-4dfd-9d49-fc56589172b2

📥 Commits

Reviewing files that changed from the base of the PR and between 0f3e75f and 13f9c56.

📒 Files selected for processing (9)

CHANGELOG.md
docs/examples/simulation_parameters.md
docs/examples/trapped_ion.md
src/mqt/yaqs/core/data_structures/mps.py
src/mqt/yaqs/core/data_structures/simulation_parameters.py
src/mqt/yaqs/core/libraries/gate_library.py
tests/core/data_structures/test_mpo.py
tests/core/data_structures/test_mps.py
tests/core/data_structures/test_simulation_parameters.py

linusschulte and others added 2 commits July 8, 2026 08:19

Added non-qubit local observables to facilitate trapped-ion position …

f873d59

…measurement

adjusted changelog

70009df

Signed-off-by: linusschulte <119408387+linusschulte@users.noreply.github.com>

aaronleesander added the feature New feature or request label Jul 8, 2026

linusschulte requested a review from aaronleesander July 8, 2026 07:34

linusschulte and others added 9 commits July 29, 2026 17:09

adjusted changelog

efd1d99

added tests to satisfy code coverage

d38154d

Merge branch 'main' into trapped-ion-hamiltonian

c04b7d8

Signed-off-by: linusschulte <119408387+linusschulte@users.noreply.github.com>

🎨 pre-commit fixes

ad1a58a

made positions a named observable type requiring appropriate kwargs

d9d1cf6

Merge branch 'main' into trapped-ion-hamiltonian

682aa7c

Signed-off-by: linusschulte <119408387+linusschulte@users.noreply.github.com>

🎨 pre-commit fixes

0ec45fe

add test coverage

c1adc2e

Merge branch 'main' into trapped-ion-hamiltonian

13f9c56

Signed-off-by: linusschulte <119408387+linusschulte@users.noreply.github.com>

coderabbitai Bot requested changes Jul 30, 2026

View reviewed changes

Comment thread src/mqt/yaqs/core/data_structures/mps.py

Comment thread src/mqt/yaqs/core/libraries/gate_library.py Outdated

address minor stability feedback

5c01f4f

coderabbitai Bot approved these changes Jul 30, 2026

View reviewed changes

aaronleesander changed the title ~~Added non-qubit local observables~~ added custom one-site matrix observables for non-qubit local dimensions , including named position observables Jul 30, 2026

aaronleesander changed the title ~~added custom one-site matrix observables for non-qubit local dimensions , including named position observables~~ added custom one-site matrix observables for non-qubit local dimensions, including named position observables Jul 30, 2026

aaronleesander merged commit 93430db into munich-quantum-toolkit:main Jul 30, 2026
14 checks passed

Navigation Menu

Uh oh!

Uh oh!

added custom one-site matrix observables for non-qubit local dimensions, including named position observables - #497

added custom one-site matrix observables for non-qubit local dimensions, including named position observables #497
aaronleesander merged 12 commits into
munich-quantum-toolkit:mainfrom
linusschulte:trapped-ion-hamiltonian

linusschulte commented Jul 8, 2026 •

edited by aaronleesander

Loading

Uh oh!

aaronleesander commented Jul 8, 2026

Uh oh!

codecov Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

linusschulte commented Jul 8, 2026

Uh oh!

aaronleesander commented Jul 30, 2026

Uh oh!

coderabbitai Bot commented Jul 30, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 30, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

linusschulte commented Jul 8, 2026 • edited by aaronleesander Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

aaronleesander commented Jul 8, 2026

Uh oh!

codecov Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

linusschulte commented Jul 8, 2026

Uh oh!

aaronleesander commented Jul 30, 2026

Uh oh!

coderabbitai Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

linusschulte commented Jul 8, 2026 •

edited by aaronleesander

Loading

codecov Bot commented Jul 8, 2026 •

edited

Loading

coderabbitai Bot commented Jul 30, 2026 •

edited

Loading

coderabbitai Bot commented Jul 30, 2026 •

edited

Loading